home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / PInterfaces / CodeFragments.p < prev    next >
Encoding:
Text File  |  1997-08-12  |  14.2 KB  |  497 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        CodeFragments.p
  3.  
  4.      Contains:    Public Code Fragment Manager Interfaces.
  5.  
  6.      Version:    Technology:    System 7
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1992-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT CodeFragments;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __CODEFRAGMENTS__}
  28. {$SETC __CODEFRAGMENTS__ := 1}
  29.  
  30. {$I+}
  31. {$SETC CodeFragmentsIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __TYPES__}
  35. {$I Types.p}
  36. {$ENDC}
  37. {$IFC UNDEFINED __FILES__}
  38. {$I Files.p}
  39. {$ENDC}
  40.  
  41.  
  42. {$PUSH}
  43. {$ALIGN MAC68K}
  44. {$LibExport+}
  45.  
  46. {
  47.    §
  48.    ===========================================================================================
  49.    Universal types and constants
  50.    =============================
  51. }
  52.  
  53.  
  54.  
  55. CONST
  56.     kCFragResourceType            = 'cfrg';
  57.     kCFragResourceID            = 0;
  58.     kCFragLibraryFileType        = 'shlb';
  59.     kCFragAllFileTypes            = $FFFFFFFF;
  60.  
  61.  
  62.  
  63. TYPE
  64.     CFragArchitecture                    = OSType;
  65.  
  66. CONST
  67.     kPowerPCCFragArch            = 'pwpc';
  68.     kMotorola68KCFragArch        = 'm68k';
  69.     kAnyCFragArch                = $3F3F3F3F;
  70.  
  71. {$IFC TARGET_CPU_PPC }
  72.     kCompiledCFragArch            = 'pwpc';
  73.  
  74. {$ENDC}  {TARGET_CPU_PPC}
  75.  
  76. {$IFC TARGET_CPU_68K }
  77.     kCompiledCFragArch            = 'm68k';
  78.  
  79. {$ENDC}  {TARGET_CPU_68K}
  80.  
  81.  
  82. TYPE
  83.     CFragVersionNumber                    = UInt32;
  84.  
  85. CONST
  86.     kNullCFragVersion            = 0;
  87.     kWildcardCFragVersion        = $FFFFFFFF;
  88.  
  89.  
  90.  
  91. TYPE
  92.     CFragUsage                            = UInt8;
  93.  
  94. CONST
  95.     kImportLibraryCFrag            = 0;                            {  Standard CFM import library. }
  96.     kApplicationCFrag            = 1;                            {  MacOS application. }
  97.     kDropInAdditionCFrag        = 2;                            {  Application or library private extension/plug-in }
  98.     kStubLibraryCFrag            = 3;                            {  Import library used for linking only }
  99.     kWeakStubLibraryCFrag        = 4;                            {  Import library used for linking only and will be automatically weak linked }
  100.  
  101.  
  102.     kIsCompleteCFrag            = 0;                            {  A "base" fragment, not an update. }
  103.     kFirstCFragUpdate            = 1;                            {  The first update, others are numbered 2, 3, ... }
  104.  
  105.  
  106.     kCFragGoesToEOF                = 0;
  107.  
  108.  
  109.  
  110.  
  111.  
  112. TYPE
  113.     CFragLocatorKind                    = UInt8;
  114.  
  115. CONST
  116.     kMemoryCFragLocator            = 0;                            {  Container is already addressable. }
  117.     kDataForkCFragLocator        = 1;                            {  Container is in a file's data fork. }
  118.     kResourceCFragLocator        = 2;                            {  Container is in a file's resource fork. }
  119.  
  120.  
  121. {
  122.    --------------------------------------------------------------------------------------
  123.    A 'cfrg' resource consists of a header followed by a sequence of variable length
  124.    members.  The constant kDefaultCFragNameLen only provides for a legal ANSI declaration
  125.    and for a reasonable display in a debugger.  The actual name field is cut to fit.
  126.    There may be "extensions" after the name, the memberSize field includes them.  The
  127.    general form of an extension is a 16 bit type code followed by a 16 bit size in bytes.
  128.    Only one standard extension type is defined at present, it is used by SOM's searching
  129.    mechanism.
  130. }
  131.  
  132.  
  133.  
  134. TYPE
  135.     CFragUsage1UnionPtr = ^CFragUsage1Union;
  136.     CFragUsage1Union = RECORD
  137.         CASE INTEGER OF
  138.                                                                         {  ! Meaning differs depending on value of "usage". }
  139.         0: (
  140.             appStackSize:        UInt32;                                    {  If the fragment is an application. (Not used by CFM!) }
  141.             );
  142.     END;
  143.  
  144.     CFragUsage2UnionPtr = ^CFragUsage2Union;
  145.     CFragUsage2Union = RECORD
  146.         CASE INTEGER OF
  147.                                                                         {  ! Meaning differs depending on value of "usage". }
  148.         0: (
  149.             appSubdirID:        SInt16;                                    {  If the fragment is an application. }
  150.             );
  151.     END;
  152.  
  153.     CFragWhere1UnionPtr = ^CFragWhere1Union;
  154.     CFragWhere1Union = RECORD
  155.         CASE INTEGER OF
  156.                                                                         {  ! Meaning differs depending on value of "where". }
  157.         0: (
  158.             spaceID:            UInt32;                                    {  If the fragment is in memory.  (Actually an AddressSpaceID.) }
  159.             );
  160.         1: (
  161.             forkKind:            OSType;                                    {  If the fragment is in an arbitrary byte stream fork. }
  162.             );
  163.     END;
  164.  
  165.     CFragWhere2UnionPtr = ^CFragWhere2Union;
  166.     CFragWhere2Union = RECORD
  167.         CASE INTEGER OF
  168.                                                                         {  ! Meaning differs depending on value of "where". }
  169.         0: (
  170.             forkInstance:        UInt16;                                    {  If the fragment is in an arbitrary byte stream fork. }
  171.             );
  172.     END;
  173.  
  174.  
  175. CONST
  176.     kDefaultCFragNameLen        = 16;
  177.  
  178.  
  179.  
  180. TYPE
  181.     CFragResourceMemberPtr = ^CFragResourceMember;
  182.     CFragResourceMember = RECORD
  183.         architecture:            CFragArchitecture;
  184.         reservedA:                UInt16;                                    {  ! Must be zero! }
  185.         reservedB:                SInt8;                                    {  ! Must be zero! }
  186.         updateLevel:            SInt8;
  187.         currentVersion:            CFragVersionNumber;
  188.         oldDefVersion:            CFragVersionNumber;
  189.         uUsage1:                CFragUsage1Union;
  190.         uUsage2:                CFragUsage2Union;
  191.         usage:                    SInt8;
  192.         where:                    SInt8;
  193.         offset:                    UInt32;
  194.         length:                    UInt32;
  195.         uWhere1:                CFragWhere1Union;
  196.         uWhere2:                CFragWhere2Union;
  197.         extensionCount:            UInt16;                                    {  The number of extensions beyond the name. }
  198.         memberSize:                UInt16;                                    {  Size in bytes, includes all extensions. }
  199.         name:                    PACKED ARRAY [0..15] OF UInt8;            {  ! Actually a sized PString. }
  200.     END;
  201.  
  202.     CFragResourceExtensionHeaderPtr = ^CFragResourceExtensionHeader;
  203.     CFragResourceExtensionHeader = RECORD
  204.         extensionKind:            UInt16;
  205.         extensionSize:            UInt16;
  206.     END;
  207.  
  208.     CFragResourceSearchExtensionPtr = ^CFragResourceSearchExtension;
  209.     CFragResourceSearchExtension = RECORD
  210.         header:                    CFragResourceExtensionHeader;
  211.         libKind:                OSType;
  212.         qualifiers:                SInt8;                                    {  ! Actually four PStrings. }
  213.     END;
  214.  
  215.  
  216. CONST
  217.     kCFragResourceSearchExtensionKind = $30EE;
  218.  
  219.  
  220.  
  221. TYPE
  222.     CFragResourcePtr = ^CFragResource;
  223.     CFragResource = RECORD
  224.         reservedA:                UInt32;                                    {  ! Must be zero! }
  225.         reservedB:                UInt32;                                    {  ! Must be zero! }
  226.         reservedC:                UInt16;                                    {  ! Must be zero! }
  227.         version:                UInt16;
  228.         reservedD:                UInt32;                                    {  ! Must be zero! }
  229.         reservedE:                UInt32;                                    {  ! Must be zero! }
  230.         reservedF:                UInt32;                                    {  ! Must be zero! }
  231.         reservedG:                UInt32;                                    {  ! Must be zero! }
  232.         reservedH:                UInt16;                                    {  ! Must be zero! }
  233.         memberCount:            UInt16;
  234.         firstMember:            CFragResourceMember;
  235.     END;
  236.  
  237.  
  238. CONST
  239.     kCurrCFragResourceVersion    = 1;
  240.  
  241.  
  242.  
  243.  
  244. TYPE
  245.     CFragConnectionID = ^LONGINT;
  246.     CFragClosureID = ^LONGINT;
  247.     CFragContainerID = ^LONGINT;
  248.     CFragContextID = ^LONGINT;
  249.     CFragLoadOptions                    = UInt32;
  250.  
  251. CONST
  252.     kReferenceCFrag                = $0001;                        {  Try to use existing copy, increment reference counts. }
  253.     kFindCFrag                    = $0002;                        {  Try find an existing copy, do not increment reference counts. }
  254.     kPrivateCFragCopy            = $0005;                        {  Prepare a new private copy. }
  255.  
  256.  
  257.     kUnresolvedCFragSymbolAddress = 0;
  258.  
  259.  
  260.  
  261. TYPE
  262.     CFragSymbolClass                    = UInt8;
  263.  
  264. CONST
  265.     kCodeCFragSymbol            = 0;
  266.     kDataCFragSymbol            = 1;
  267.     kTVectorCFragSymbol            = 2;
  268.     kTOCCFragSymbol                = 3;
  269.     kGlueCFragSymbol            = 4;
  270.  
  271.  
  272.  
  273. {
  274.    §
  275.    ===========================================================================================
  276.    System 7 Services 
  277.    ==========================================
  278. }
  279.  
  280.  
  281.  
  282. {
  283.    ---------------------------------------------------------------------------------
  284.    These declarations are for System 7 and the System 8 cooperative environment, but
  285.    should be avoided under System 8.  Better alternatives exist for System 8.
  286. }
  287.  
  288.  
  289. FUNCTION GetSharedLibrary(libName: ConstStr63Param; archType: CFragArchitecture; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr;
  290.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  291.     INLINE $3F3C, $0001, $AA5A;
  292.     {$ENDC}
  293. FUNCTION GetDiskFragment({CONST}VAR fileSpec: FSSpec; offset: UInt32; length: UInt32; fragName: ConstStr63Param; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr;
  294.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  295.     INLINE $3F3C, $0002, $AA5A;
  296.     {$ENDC}
  297. FUNCTION GetMemFragment(memAddr: UNIV Ptr; length: UInt32; fragName: ConstStr63Param; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr;
  298.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  299.     INLINE $3F3C, $0003, $AA5A;
  300.     {$ENDC}
  301. FUNCTION CloseConnection(VAR connID: CFragConnectionID): OSErr;
  302.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  303.     INLINE $3F3C, $0004, $AA5A;
  304.     {$ENDC}
  305. FUNCTION FindSymbol(connID: CFragConnectionID; symName: ConstStr255Param; VAR symAddr: Ptr; VAR symClass: CFragSymbolClass): OSErr;
  306.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  307.     INLINE $3F3C, $0005, $AA5A;
  308.     {$ENDC}
  309. FUNCTION CountSymbols(connID: CFragConnectionID; VAR symCount: LONGINT): OSErr;
  310.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  311.     INLINE $3F3C, $0006, $AA5A;
  312.     {$ENDC}
  313. FUNCTION GetIndSymbol(connID: CFragConnectionID; symIndex: LONGINT; VAR symName: Str255; VAR symAddr: Ptr; VAR symClass: CFragSymbolClass): OSErr;
  314.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  315.     INLINE $3F3C, $0007, $AA5A;
  316.     {$ENDC}
  317.  
  318. {
  319.    §
  320.    ===========================================================================================
  321.    Initialization & Termination Routines
  322.    =====================================
  323. }
  324.  
  325.  
  326. {
  327.    -----------------------------------------------------------------------------------------
  328.    A fragment's initialization and termination routines are called when a new incarnation of
  329.    the fragment is created or destroyed, respectively.  Exactly when this occurs depends on
  330.    what kinds of section sharing the fragment has and how the fragment is prepared.  Import
  331.    libraries have at most one incarnation per process.  Fragments prepared with option
  332.    kPrivateCFragCopy may have many incarnations per process.
  333.    The initialization function is passed a pointer to an initialization information structure
  334.    and returns an OSErr.  If an initialization function returns a non-zero value the entire
  335.    closure of which it is a part fails.  The CFragInitBlock type has different visible parts
  336.    under System 7 and System 8, but is of course the same internally.  The C prototype for an
  337.    initialization function is:
  338.           pascal OSErr    CFragInitFunction    ( const CFragInitBlock *    initBlock );
  339.    The termination procedure takes no parameters and returns nothing.  The C prototype for a
  340.    termination procedure is:
  341.           pascal void        CFragTermProcedure    ( void );
  342. }
  343.  
  344.  
  345.  
  346. TYPE
  347.     CFragSystem7MemoryLocatorPtr = ^CFragSystem7MemoryLocator;
  348.     CFragSystem7MemoryLocator = RECORD
  349.         address:                LogicalAddress;
  350.         length:                    UInt32;
  351.         inPlace:                BOOLEAN;
  352.         reservedA:                SInt8;                                    {  ! Must be zero! }
  353.         reservedB:                UInt16;                                    {  ! Must be zero! }
  354.     END;
  355.  
  356.     CFragSystem7DiskFlatLocatorPtr = ^CFragSystem7DiskFlatLocator;
  357.     CFragSystem7DiskFlatLocator = RECORD
  358.         fileSpec:                FSSpecPtr;
  359.         offset:                    UInt32;
  360.         length:                    UInt32;
  361.     END;
  362.  
  363. {  ! This must have a file specification at the same offset as a disk flat locator! }
  364.     CFragSystem7SegmentedLocatorPtr = ^CFragSystem7SegmentedLocator;
  365.     CFragSystem7SegmentedLocator = RECORD
  366.         fileSpec:                FSSpecPtr;
  367.         rsrcType:                OSType;
  368.         rsrcID:                    SInt16;
  369.         reservedA:                UInt16;                                    {  ! Must be zero! }
  370.     END;
  371.  
  372.     CFragSystem7LocatorPtr = ^CFragSystem7Locator;
  373.     CFragSystem7Locator = RECORD
  374.         where:                    SInt32;
  375.         CASE INTEGER OF
  376.         0: (
  377.             onDisk:                CFragSystem7DiskFlatLocator;
  378.             );
  379.         1: (
  380.             inMem:                CFragSystem7MemoryLocator;
  381.             );
  382.         2: (
  383.             inSegs:                CFragSystem7SegmentedLocator;
  384.             );
  385.     END;
  386.  
  387.     CFragSystem7InitBlockPtr = ^CFragSystem7InitBlock;
  388.     CFragSystem7InitBlock = RECORD
  389.         contextID:                CFragContextID;
  390.         closureID:                CFragClosureID;
  391.         connectionID:            CFragConnectionID;
  392.         fragLocator:            CFragSystem7Locator;
  393.         libName:                StringPtr;
  394.         reservedA:                UInt32;                                    {  ! Must be zero! }
  395.     END;
  396.  
  397.     CFragInitBlock                        = CFragSystem7InitBlock;
  398.     CFragInitBlockPtr                     = ^CFragInitBlock;
  399.     CFragInitFunction = ProcPtr;  { FUNCTION CFragInitFunction((CONST)VAR initBlock: CFragInitBlock): OSErr; C; }
  400.  
  401.     CFragTermProcedure = ProcPtr;  { PROCEDURE CFragTermProcedure; C; }
  402.  
  403. {
  404.    §
  405.    ===========================================================================================
  406.    Old Name Spellings
  407.    ==================
  408. }
  409.  
  410.  
  411. {
  412.    -------------------------------------------------------------------------------------------
  413.    We've tried to reduce the risk of name collisions in the future by introducing the phrase
  414.    "CFrag" into constant and type names.  The old names are defined below in terms of the new.
  415. }
  416.  
  417.  
  418.  
  419. CONST
  420.     kLoadCFrag                    = $0001;                        {  ! Keep kLoadCFrag visible to compilers! }
  421.  
  422.  
  423. {$IFC OLDROUTINENAMES }
  424.  
  425. TYPE
  426.     ConnectionID                        = CFragConnectionID;
  427.     LoadFlags                            = CFragLoadOptions;
  428.     SymClass                            = CFragSymbolClass;
  429.     InitBlock                            = CFragInitBlock;
  430.     InitBlockPtr                         = ^InitBlock;
  431.     MemFragment                            = CFragSystem7MemoryLocator;
  432.     MemFragmentPtr                         = ^MemFragment;
  433.     DiskFragment                        = CFragSystem7DiskFlatLocator;
  434.     DiskFragmentPtr                     = ^DiskFragment;
  435.     SegmentedFragment                    = CFragSystem7SegmentedLocator;
  436.     SegmentedFragmentPtr                 = ^SegmentedFragment;
  437.     FragmentLocator                        = CFragSystem7Locator;
  438.     FragmentLocatorPtr                     = ^FragmentLocator;
  439.     CFragHFSMemoryLocator                = CFragSystem7MemoryLocator;
  440.     CFragHFSMemoryLocatorPtr             = ^CFragHFSMemoryLocator;
  441.     CFragHFSDiskFlatLocator                = CFragSystem7DiskFlatLocator;
  442.     CFragHFSDiskFlatLocatorPtr             = ^CFragHFSDiskFlatLocator;
  443.     CFragHFSSegmentedLocator            = CFragSystem7SegmentedLocator;
  444.     CFragHFSSegmentedLocatorPtr         = ^CFragHFSSegmentedLocator;
  445.     CFragHFSLocator                        = CFragSystem7Locator;
  446.     CFragHFSLocatorPtr                     = ^CFragHFSLocator;
  447.  
  448. CONST
  449.     kPowerPCArch                = 'pwpc';
  450.     kMotorola68KArch            = 'm68k';
  451.     kAnyArchType                = $3F3F3F3F;
  452.     kNoLibName                    = 0;
  453.     kNoConnectionID                = 0;
  454.     kLoadLib                    = $0001;
  455.     kFindLib                    = $0002;
  456.     kNewCFragCopy                = $0005;
  457.     kLoadNewCopy                = $0005;
  458.     kUseInPlace                    = $80;
  459.     kCodeSym                    = 0;
  460.     kDataSym                    = 1;
  461.     kTVectSym                    = 2;
  462.     kTOCSym                        = 3;
  463.     kGlueSym                    = 4;
  464.     kInMem                        = 0;
  465.     kOnDiskFlat                    = 1;
  466.     kOnDiskSegmented            = 2;
  467.     kIsLib                        = 0;
  468.     kIsApp                        = 1;
  469.     kIsDropIn                    = 2;
  470.     kFullLib                    = 0;
  471.     kUpdateLib                    = 1;
  472.     kWholeFork                    = 0;
  473.     kCFMRsrcType                = 'cfrg';
  474.     kCFMRsrcID                    = 0;
  475.     kSHLBFileType                = 'shlb';
  476.     kUnresolvedSymbolAddress    = 0;
  477.  
  478.     kPowerPC                    = 'pwpc';
  479.     kMotorola68K                = 'm68k';
  480.  
  481. {$ENDC}  {OLDROUTINENAMES}
  482.  
  483.  
  484.  
  485.  
  486.  
  487. {$ALIGN RESET}
  488. {$POP}
  489.  
  490. {$SETC UsingIncludes := CodeFragmentsIncludes}
  491.  
  492. {$ENDC} {__CODEFRAGMENTS__}
  493.  
  494. {$IFC NOT UsingIncludes}
  495.  END.
  496. {$ENDC}
  497.